%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% estimateSoundTrackBounds.m
% getSoundTrackBoundsManually.m
% writeToLogFile.m
% Image processing toolbox
%
% Any file used by the particular function whose handle is passed in the
% input argument "readFramesFunctHandle". Those may include:
% patientlyKeepTryingToReadUntilErrorFree.m
% readAndCheckVideoFrames.m
% readImageFile.m
% readImagesByIndexRange.m
% readdpx.m
%
%==========================================================================

%==========================================================================
% The function "getSoundTrackBounds" estimates the left and right bounds of
% the sound track region in a sequence of frames.
% INPUT: "readFramesFunctHandle" is a handle to a function capable of
% reading any range of frames from a preset source.
% "frameRange" is a single integer or a row vector of two integers
% specifying the index of a single frame or a range of frames to be read
% from a preset source.
% "numTestFrames" is an integers specifying the number of frames to be
% drawn at random from the pool of all available frames and used directly
% for estimation of the sound track bounds.
% "filmStandard" is an optional string specifying the format of the
% original film from which the frames came. This information is used to set
% approximate soundtrack bounds likely to be close to the actual bounds.
% OUTPUT: "leftBound" and "rightBound" return the left and right vertical
% bounds of the sound track region in the given frames.
%==========================================================================
function [leftBound, rightBound] = getSoundTrackBounds(readFramesFunctHandle, ...
    frameRange, numTestFrames, filmStandard) 

if (nargin < 4)
    filmStandard = '';
end
if (nargin < 3) 
    numTestFrames = 5; 
end 

% Use an automated approach to estimate the left and right vertical bounds
% of the sound track region in the frame sequence. These estimates are to
% be evaluated and corrected interactively as implemented in the code
% below.
[leftBound, rightBound] = estimateSoundTrackBounds(readFramesFunctHandle, frameRange, filmStandard);

% Draw a number of random indices from those allowed and sort them in
% increasing order.
randFrameIndArr = sort(randi([frameRange(1), frameRange(end)], numTestFrames, 1), 'ascend');

% Interactively determine the left and right vertical bounds of the sound
% track region.
[leftBound, rightBound] = getSoundTrackBoundsManually(readFramesFunctHandle, ...
    randFrameIndArr, leftBound, rightBound);

return;
% end of the function "getSoundTrackBounds"
